# [OPS-MAN-059] 文档 · PDF 与 HTML 生成与查看
> **参考手册** · 把 `docs/` 里的 markdown 变成**好看、可打印、可离线**的 HTML / PDF，一条线讲清。
>
> **一句话定位**：仓库里的 `.md` 是**唯一真源**；`.html` / `.pdf` 是从它**确定性生成的产物**。
> 想读得舒服（浮动目录、表格、代码块、中文字体）就生成 HTML；想归档 / 打印 / 发给别人就生成 PDF。
>
> 相关：`tools/khyos-markdown/`（右键打开任意 `.md` 的交互工作台）、
> [IMPL-RPT-023] 文档排版-内容与样式分离、[DESIGN-ARCH-032] 内嵌 MD 工作台、
> [DESIGN-ARCH-023] 文档排版与格式控制规范。
---
## 0. 先分清三条路（选对工具，别绕路）
| 我想做的 | 用哪个 | 产物 |
| --- | --- | --- |
| **随手读某个 `.md`**（阅读 / 小改） | `tools/khyos-markdown`（右键或命令打开） | 浏览器里实时预览，不落文件 |
| **把 `docs/` 文档生成漂亮 HTML / PDF** | `scripts/docs/md-to-pdf.js` | 自带样式的 `.html` + 打印版 `.pdf` |
| **让 AI 排版一篇论文 / 报告（Word）** | `renderDocument` 工具（REPL 内） | `.docx`（**注意：不产 PDF/HTML**，见 §4） |
> 记住这条分界：**读文档 → khyosMarkdown；发布/归档文档 → md-to-pdf.js；写正式 Word → renderDocument。**
> 本文主讲前两条（PDF / HTML），第三条只做澄清避免混淆。
```svg
```
> 上图：同一份 `.md` 真源，按目的分流到三条路；三种产物各不重叠（`renderDocument` 只产 `.docx`，见 §4）。
---
## 1. 生成 HTML + PDF（最常用）
真源脚本：`scripts/docs/md-to-pdf.js`。**零新增依赖**——复用仓库已内置的 `markdown-it`
（`extensions/khy-trae-bridge/node_modules/markdown-it`）解析 markdown，用系统的 **google-chrome
`--print-to-pdf`** 把生成的 HTML 打成 PDF。中文靠 Noto Sans/Serif CJK 渲染。
```svg
```
### 1.1 一个文件 → HTML + PDF
```bash
# 在仓库根目录执行
node scripts/docs/md-to-pdf.js "docs/07_OPS_运维/[OPS-MAN-037] pip安装后-完整还原与全功能开启指南.md"
```
默认在**源文件旁边**写出同名 `.html` 与 `.pdf`，并打印实际写出的路径。
### 1.2 常用选项
| 选项 | 作用 |
| --- | --- |
| `--out-dir <目录>` | 产物写到指定目录（默认：与源 `.md` 同目录） |
| `--html-only` | 只出 HTML，跳过 PDF（**没装 chrome 时用它**） |
| `--pdf-only` | 只出 PDF（内部仍会临时渲染一份 HTML，用完删） |
| `--combined "标题" 基名 a.md b.md ...` | 把多篇合成**一本**（带分页），生成 `基名.html` / `基名.pdf` |
| `--preset onboarding` | 一键重生成「使用入门→开发精通」成长路线全套（见 §3） |
### 1.3 批量 / 合订本
```bash
# 多个文件各自出一份
node scripts/docs/md-to-pdf.js a.md b.md c.md --out-dir /tmp/docs-out
# 合成一本（自动在每篇之间分页；目录汇总所有小节）
node scripts/docs/md-to-pdf.js --combined "运维手册合订本" 运维手册合订 \
"docs/07_OPS_运维/[OPS-MAN-037] ....md" \
"docs/07_OPS_运维/[OPS-MAN-032] ....md"
```
---
## 2. 没有 Chrome？两条退路
PDF 这一步依赖 headless Chrome。缺它时脚本会**明确报错**（不静默失败），有三种处理：
1. **装 chrome**（推荐）：装 `google-chrome` / `chromium` 任一即可，脚本自动探测。
2. **指到你已有的 chrome**：设环境变量 `KHY_DOCS_CHROME`（或 `CHROME_PATH`）指向浏览器可执行文件。
```bash
export KHY_DOCS_CHROME="/usr/bin/chromium"
node scripts/docs/md-to-pdf.js "docs/....md"
```
探测顺序：`KHY_DOCS_CHROME` → `CHROME_PATH` → `google-chrome-stable` → `google-chrome`
→ `chromium` → `chromium-browser` → macOS 的 `Google Chrome.app`。
3. **只出 HTML，自己手动转 PDF**：
```bash
node scripts/docs/md-to-pdf.js "docs/....md" --html-only
```
然后在任意浏览器打开该 `.html` → `Ctrl/Cmd + P` → 目标选「**另存为 PDF**」。
生成的 HTML **内置了打印样式**（`@media print` / `@page A4`：隐藏浮动目录、A4 页边距、
代码/表格避免跨页断开），所以浏览器打印出来的版式与脚本自动生成的 PDF 基本一致。
> Chrome 打印参数（脚本内固定）：`--headless=new --no-pdf-header-footer
> --run-all-compositor-stages-before-draw --virtual-time-budget=15000`；老版本 chrome 拒绝
> `--headless=new` 时自动回退经典 `--headless`。**任一步失败都以真实原因非零退出**，不掩盖。
---
## 3. 一键重生成成长路线全套（preset）
`OPS-MAN-043` / `OPS-MAN-044` 这两篇「成长路线」文档常一起分发，脚本内置了 `onboarding` 预设，
把两篇各出一份独立 HTML/PDF，再合成一本合订本：
```bash
node scripts/docs/md-to-pdf.js --preset onboarding
```
产物（写在 `docs/07_OPS_运维/` 下）：
- `[OPS-MAN-043] ....html` / `.pdf`
- `[OPS-MAN-044] ....html` / `.pdf`
- `[OPS-MAN-043+044] 从使用入门到开发精通-合订本.html` / `.pdf`
> 预设的源清单是**单一真源**（脚本内 `ONBOARDING_DOCS`）。改了这两篇 `.md` 后重跑此命令即可刷新产物；
> 产物**永远从 `.md` 重生**，别手改 `.html` / `.pdf`（会被下次生成覆盖）。
---
## 4. 澄清：`renderDocument` 产的是 Word，不是 PDF/HTML
REPL 里的 `renderDocument`（别名 `typeset_document` / `render_docx` 等）是给 AI 写**论文/正式报告**用的
「内容与样式分离」排版器：模型只产语义内容，程序按模板确定性排版，**产物是 `.docx`（Word）**。
它**不产 PDF / HTML** —— 若要 PDF，请用 Word/WPS/LibreOffice 打开 `.docx` 后另存为 PDF。
- 设计动机与实现见 [IMPL-RPT-023]（内容与样式分离）、[DESIGN-ARCH-023]（排版规范）。
- 真源：`services/backend/src/tools/renderDocument.js` + `src/templates/docstyles/*.json`。
所以：**文档站点用的漂亮 HTML/PDF → §1 的 `md-to-pdf.js`；AI 写 Word 论文 → `renderDocument`。** 两条路各司其职。
---
## 5. 交互阅读：khyosMarkdown 工作台
只想**读**或**小改**某个 `.md`（不生成产物），用 `tools/khyos-markdown`：单文件、零外部依赖、断网可用，
经本机回环桥接器绕过 `file://` 的 CORS 限制（细节见 `tools/khyos-markdown/README.md`）。
```bash
# 打开任意 .md（自动起本机服务 + 开浏览器）
node tools/khyos-markdown/khyos-md-bridge.js "/path/to/任意 文档.md"
# 无参 → 浏览本仓库 docs/
node tools/khyos-markdown/khyos-md-bridge.js
```
注册系统右键「使用 khyosMarkdown 打开」（Windows 仅 HKCU、Linux 仅 `~/.local`，无 UAC / sudo）：
```bash
# Linux
bash tools/khyos-markdown/register-linux.sh
# Windows（PowerShell，无需管理员）
powershell -ExecutionPolicy Bypass -File tools/khyos-markdown/register-windows.ps1
```
> 想从工作台得到 PDF：浏览器里 `Ctrl/Cmd + P` → 另存为 PDF 即可；要归档级、带目录的排版版，仍推荐走 §1 的脚本。
---
## 6. 生成 HTML 的交互与图解特性
`md-to-pdf.js` 产出的 HTML 不只是"能看"，还内置了一批**在浏览器里交互、打印时自动降级**的能力
（全部内联，无 CDN、无外部 JS，断网可用）：
```svg
```
| 特性 | 行为 | 打印（PDF）时 |
| --- | --- | --- |
| **目录高亮** | 滚动时当前小节在左侧目录里高亮（IntersectionObserver） | 目录本就隐藏，无影响 |
| **标题永久链接** | 悬停 `h2/h3` 显示 `#`，点击即定位并可复制该锚点 URL | 隐藏 `#`，标题干净 |
| **回到顶部** | 滚过约 400px 出现右下角圆钮，点击平滑回顶 | 隐藏按钮 |
| **跨文档引用** | 正文里的 `[OPS-MAN-037]` 等编号**自动**变成指向同目录 `.html` 的链接 | 变普通文字（无下划线色块） |
| **内联 SVG 图解** | markdown 里的 ` ```svg ` 代码块**直接渲染成矢量图** | 矢量图打印清晰、避免跨页断开 |
**内联 SVG 怎么写**：在 `.md` 里用 ` ```svg ` 围栏包一段**手写 `